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Section 1. Introduction 


Road map 

This tutorial expands on the topics discussed in the introductory article, Coding Palm 
OS, which discusses the required development environment for creating Palm OS 
applications. This tutorial demonstrates the entire build cycle and verifies the toolset 
installation by building a complete Palm OS application. It concludes with a few build 
environment tips and a preview of the next tutorial, which covers advanced Palm OS 
programming topics, including database access and serial communications. 

This tutorial is organized into the following sections: 

* Acquisition of development tools 

* Examination of Palm OS application architecture 

* Simple application build and test 

* Build environment topics and preview of upcoming tutorials 


Code examples index 

Code snippets in this tutorial demonstrate fundamental Palm OS application 
functionality, including the use of the Palm OS Software Development Kit (SDK). The 
code snippets include: 

* PilotMain - This is the entry point for all Palm OS applications, and as such is a 
good starting point for an introduction to the Palm OS application architecture. 

* EventLoop -- Under normal operation of an application, the EventLoop is 
responsible for dispatching all events received from the operating system. 
Understanding the event-based architecture and the underlying responsibilities of 
the event handler is a key skill in developing applications. 

* FrmMain_HandleEvent - Basic user interface event handling is a required skill in 
Palm OS development. FrmMain_HandleEvent provides the necessary code to 
handle simple user interface interactions. 

* Various data type explanations - The data types commonly used in Palm OS 
development are compared to similar data types on other platforms. 

* Makefile dissection - Underlying the IDE project is a complete makefile, 
compatible with the GNU tools. 

* Static library creation and use - Static libraries are convenient code archives. 
This demonstrates creating a static library with the GNU tools. 

The full source code is available for download. See the Further resources on page 20 
section at the end of this article for details. 


Conventions used in this tutorial 

* Text to be typed in is displayed in a bold monospace font. In some code 
examples, bold is used to draw attention to a tag or element being referenced in 
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the accompanying text. 

* Emphasis is used to draw attention to windows, dialog boxes, feature names, and 
key terms. 

* A monospace font represents file and path names, as well as coding examples. 

* Throughout this tutorial, code segments irrelevant to the discussion have been 
omitted and replaced with ellipses (...). 


About the author 

After his college basketball career came to an end without a multiyear contract to play 
for the L.A. Lakers, Frank Ableson shifted his focus to computer software design. Fie 
enjoys solving complex problems, particularly in the areas of communications and 
hardware interfacing. When not working, he can be found spending time with his wife 
Nikki and their children. Frank can be reached at frank@cfgsolutions.com. 
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Section 2. Acquisition of development tools 
The requirements and the choice 

As mentioned in Coding Palm OS, there are three prominent choices for C language 
development: CodeWarrior for Palm OS, the open source PRC-Tools, and Falch.net's 
Developer Studio. Before discussing which tool to employ, there is the question: "Why 
use C and not another language?" Any conceivable Palm OS application can be built 
with C language tools. The reason for this is C's tools leverage the full Palm OS SDK. 
They also provide necessary hooks into the operating system in the form of function 
callbacks, shared libraries, and trap-hooking mechanisms. Additionally, these tools 
produce a native Palm OS application, not an interpreted, pseudo-code program. There 
are no virtual machines or language interpreters. While this fact alone does not 
guarantee a high-performance application, it does mean that there is little overhead 
when running a "C" application and fewer moving parts to maintain on the device itself. 


Falch.net's Developer Studio and PRC-Tools 

Falch.net's Developer Studio was chosen for use in this tutorial for its clean packaging, 
compatibility, and ease of use. An attractive feature of Developer Studio is its 
integration with and use of the open source PRC-Tools suite. This compatibility permits 
the use of various GNU tools and utilities such as make. Projects created with 
Developer Studio can be compiled from the command line with make. Additionally, 
source-code management of a PRC/Developer Studio project fits nicely with existing 
tools in many programming shops. These features are helpful to developers who port 
their products to the Palm OS. Falch.net's context-sensitive help system, which also 
provides "tool tips" function prototypes, is a nice bonus, particularly for the beginner. 
Falch.net's Developer Studio is a modern Windows-based integrated development 
environment (IDE). 


CodeWarrior for Palm OS 

How about CodeWarrior? CodeWarrior's roots lie with the Motorola family of 
microprocessors, such as those found in Macintoshes and PowerPCs. Some of the 
data formats are compatible with the Mac OS platform. A CodeWarrior projects' 
proprietary data formats present challenges to traditional source-code management, to 
the development of a common code base for multiple target-platform support, and to 
performing automatic builds. Mac OS developers are encouraged to check out 
CodeWarrior. 


Any will suffice 

As in politics, there is not always a clear choice to be made. All three C language tool 
suites provide the necessary ingredients to build any Palm OS application. The source 
presented in this tutorial will compile and run with any of the suites with little 
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modification. The user interface components are not compatible across compilers. 
There are tools to convert the user interface resource files from one environment to 
another. You can find more information on compatibility at Palm's Developer Web site 
and in the documentation for each tool set. 

The build examples at the end of this tutorial highlight PRC/Developer Studio 
compatible features. All projects are created in Falch.net Developer Studio, however 
they can be compiled and manipulated outside of the IDE with the PRC-Tools as well. 


Tool distributions 

The best source for information on Palm OS development tools is the Palm Computing 
Web site. Links to all the major development tools are available as well as in-depth 
reviews and comparisons. The next step is to choose a tool and install it. It is important 
to follow the installation directions provided with any of these tools. As mentioned 
earlier, this tutorial makes use of the Falch.net product suite. The following panels are 
a quick synopis of how to acquire and install Falch.net's Developer Studio product. 


Step one: Download the product 

Download an evaluation copy of the product from http://www.falch.net. A required 
installation password is provided via e-mail. This download enables a time-limited 
evaluation license. 


Step two: Install the suite 

The installation process installs both the IDE and the PRC-Tools suite. This is an 
important point to appreciate because the PRC-Tools installation has some critical 
elements that do not always install easily. The Falch.net installation wizard takes care 
of all these steps transparently. A "side effect" of installing Falch.net is a clean 
installation of the key PRC-Tools components. 


Step three: Download the Palm OS SDK 

Download the latest Palm OS SDK from the Palm OS Web site. The Falch.net 
installation provides a link to detailed instructions on how to install the SDK in the build 
environment. In particular, the SDK subdirectory must be renamed to properly match 
the values used during the build process. Flint: Be sure to have an active Internet 
connection during the installation. 


Step four: Load the Palm OS Emulator with a ROM 

Falch.net integrates the Palm OS Emulator (POSE) into its Developer Studio IDE. In 
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order for POSE to work properly, it must be loaded with a ROM file. ROM files are 
obtained from the Palm OS device itself using a utility known as Rom Transfer.pro, a 
Palm OS resident application. The ROM Transfer application ships with POSE and can 
be found in the C:\Program Files\Falch.net\DeveloperStudio 
2.5\bin\POSE directory. Next run emuiator.exe and choose 'Download'. Follow 
the directions listed in the window to capture the ROM image. 


Step five: Create a new project 

Create a new project under the File | New menu. Two different project types are 
offered. Choose Palm OS Framework Project. Answer the questions presented by the 
new project dialogs. Once the project source is generated, press F7 to build the 
application. Any errors or troubles with the installation appear in the output window 
found in the lower left portion of the screen. 


Exploring the SDK 

It is crucial to understand the facilities provided by the SDK as they are the lifeblood of 
Palm OS development. Documentation for Palm OS has traditionally been supplied in 
the form of Acrobat PDF files, however Falch.net makes the information available via 
context-sensitive help. Open up a source file created from the new Palm OS 
Framework Project wizard and scan the various function calls. Highlight any function 
and press the FI key for help. 

Syntax, style, and data types require some attention. SDK functions are organized into 
categories based on their role. All functions of the same category have the same two- 
or three-letter prefix. Here are some examples: 

* Frm: Form manipulation functions 

* Fid: Field manipulation functions 

* Net: Network functions 

* Exg: Exchange Manager functions, used for infrared beaming 

* Srm: (New) Serial Manager functions 


Data types 

Data types fall into two categories: scalar and composite. Scalar data types are 
variables that are not broken down into subfields. Here are some Palm OS scalar data 
types and their 'equivalent' data type in other environments: 

Ulnt8 - byte 
Char - char 
UInti 6 - word 
Inti 6 - short 
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Ulnt32 - dword 
Int32 - long 

Ulnt8* - unsigned char *, or byte * 

The other category is the composite, or user-defined data type. The 
SortRecordinfoType below is an example of this kind of data type. It uses other 
data types to construct the composite representation required. 

Here is the syntax for a data type taken from the DataMgr.h header file: 

typedef struct { 

UInt8 attributes; // record attributes; 

UInt8 uniqueID[3]; // unique ID of record 
} SortRecordinfoType; 

typedef SortRecordinfoType *SortRecordInfoPtr; 


A pointer data type is designated with a Ptr at the end, as shown above. 

Pointer variables are designated with a capital p at the end. For example, here is the 
syntax for defining a pointer to a SortRecordinfoType: 

SortRecordlnfoPtr sortinfoP; 


C runtime functions 

On most platforms it is common to utilize standard C runtime functions such as string 
manipulation routines like sprintf () or strcpy (). Palm OS provides its own 
version of these and other runtime functions. Do not attempt to use the standard C 
routines. String manipulation functions all start with str and can be found in the 
documentation. Please note that the strPrintF function is unforgiving in regard to 
data type sizes in the format string. 
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Section 3. Examination of the Palm OS application 
architecture 

A bird's eye view of the architecture 

The Palm OS is an event-based operating system. Typical events are pen taps, button 
presses, menu selections, and so forth. The operating system and the application work 
in cooperation to service the event queue. The operating system enqueues events as 
they occur. The primary responsibility of any Palm OS application is to service the 
event queue. Both the operating system and the application can service the queue. 

Both can add events, and both can remove events. 

The operating system supports a single user-interface application. Multitasking is not 
available for custom applications. There are limited "background tasks" in the operating 
system, although these are minimal and deal with low-level communications drivers. 
These drivers enable modem or network access for the device. A network connection 
takes place at a lower level than the user application, although the user application 
often initiates and terminates the underlying connection. It is perfectly feasible (and 
common) for one application to establish a connection and then terminate itself. This 
allows another application, the active user interface, to make use of the network 
connection, if so desired. This is the manner in which the Network Preferences panel 
operates. The operating system is responsible for managing the low-level 
communications driver and the single user-interface task. 


Launch codes 

There is more than one way to start an application. It can be initiated from either the 
main application launcher interface, or from another application. Launch codes are 
arguments passed to the application at startup. These launch codes permit the 
application to make appropriate decisions on how to behave and operate. For example, 
with a normal launch, the application displays its full user interface. A Find launch code 
prompts the program to search its database, but not display a user interface. 

The next few panels walk through code examples of "boilerplate" Palm OS 
applications. These sections address launch codes, the main EventLoop, and event 
handlers. These three topics are fundamental to a Palm OS application. 


PilotMain 

PilotMain is the entry point for a Palm OS application. PilotMain performs the 
same role as the main () function in other C language environments. The arguments 
to PilotMain determine the role the application is to perform. Plere is the PilotMain 
code: 


UInt32 PilotMain(UIntl6 cmd, void *cmdPBP, UIntl6 launchFlags) 
{ 

Err error; 
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switch (cmd) 

{ 

case sysAppLaunchCmdNormalLaunch: 
// Application start code 
error = StartApplication(); 
if (error) 

return error; 

// Maintain event loop 
EventLoop() ; 

// Stop application 
StopApplication() ; 
break; 
default: 

break; 

} 

return 0; 

} 


The cmd parameter represents the launch code. This code can request a normal 
launch, as this example demonstrates, or it can be one of a finite list of values. These 
values include launch codes to inform applications that the HotSync operation is 
complete or that the date or time has been changed. The SDK documentation 
enumerates all available launch codes. 


PilotMain, continued 

The parameter cmdPBP can point to a structure required for a particular launch code. 
For example, the launch code sysAppLaunchCmdGoto is used to instruct an 
application to initiate its user interface and display a particular record. The structure 
accessible via the cmdPBP parameter contains the necessary information to perform 
the action of displaying a specific database record. Here is what the structure looks 
like: 

typedef struct { 

Intl6 searchStrLen; 

UIntl6 dbCardNo; 

LocalID dbID; 

UIntl6 recordNum; 

UIntl6 matchPos; 

UIntl6 matchFieldNum; 

UInt32 matchCustom; 

} GoToParamsType; 


The launchFiags parameter allows further refinement on how the application 
operates. One interesting flag is sysAppLaunchFlagSubCall. This value allows the 
application to call its own PilotMain function again and again. 

Under a normal launch, the application performs any initialization required and then 
enters its main EventLoop. 


The EventLoop function 
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A Palm OS application's primary activity is to service events it has received from the 
operating system. This process is accomplished via a function called EventLoop. A 
typical EventLoop function is presented below: 


static void EventLoop(void) 

{ 

Err error; 

EventType event; 

// Main event loop 
do 
{ 

// Get next event 

EvtGetEvent(&event, evtWaitForever); 

// Handle event 

if (!SysHandleEvent(Sevent)) 

{ 

if (IMenuHandleEvent(0, Sevent, Serror)) 
{ 

if (!ApplicationHandleEvent(Sevent)) 
FrmDispatchEvent(Sevent); 

} 

} 

} 

while (event.eType != appStopEvent); 

} 


The EventLoop continually looks for new events by calling the EvtGetEvent 
function. Once an event has been received, the EventLoop passes the event to a 
series of event handlers. There is a priority to the event handlers, demonstrated in the 
calling sequence as events "trickle down" through various handlers. 


The event handlers 

The operating system itself is given the first opportunity to process an event. The 
operating system services events such as a hard key press. If the operating system is 
not interested in the event, the event is passed on to the MenuHandieEvent handler. 
The MenuHandieEvent function is responsible for tracking menu interaction. When a 
menu item is selected, the MenuHandieEvent function enqueues a menuEvent to the 
event queue. If both the Sys and Menu handlers decline to process an event, the event 
is passed to application-defined functions. 

The ApplicationHandleEvent function generally deals with only one event, the 
FrmLoadEvent: 


static Boolean ApplicationHandleEvent(EventPtr event) 
{ 

UIntl6 formID; 

FormPtr form; 

Boolean handled = false; 

// Application event loop 
switch (event->eType) 

{ 


case frmLoadEvent: 

// Handle form load events 

formID = event->data.frmLoad.formID; 

form = FrmInitForm(formID); 
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FrmSetActiveForm(form); 
switch (formID) 

{ 

case frmMain: 

// Set event handler for frmMain 

FrmSetEventHandler(form, (FormEventHandlerPtr) FrmMain_HandleEvent 
break; 
default: 

break; 

} 

handled = true; 
break; 
default: 

break; 

} 

return handled; 

} 

This function initializes the form and assigns the form's event handler. Cases are 
added for each additional form in order to assign the appropriate event handler 
function. 

The EventLoop function continues until it receives an appStopEvent signaling it to 
terminate. 


Form event handlers 

As an event trickles down through the series of event handlers without being serviced, 
it will eventually fall to the current form event handler. This function is 
application-defined to service relevant events. It services menu events, button selects, 
pop-up list selections, and so on. In short, the form event handler deals with 
user-interface events. Most substantive Palm OS development starts at this point. The 
other functions are more or less boilerplate code that is copied from project to project. 

Each event carries with it specific information pertinent to that event. For example, a 
button selection event contains the identifier for the button, while a pen tap contains the 
screen coordinates of the pen at the time the tap was recorded. The following code 
snippet demonstrates the handling of a button press. This application's user interface 
contains a single button called Hit Me: 


Boolean frmMain_HandleEvent(EventPtr event) 

{ 

FormPtr form; 

Boolean handled = false; 
switch (event->eType) 

{ 

case ctlSelectEvent: 

switch (event->data.ctlSelect.controlID) 

{ 

// HitMe receives an event 
case HitMe: 

handled = frmMain_HitMe_OnSelect(event); 
break; 

} 

break; 

case frmOpenEvent: 
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// Repaint form on open 
form = FrmGetActiveForm(); 
FrmDrawForm(form); 
handled = true; 
break; 
default: 

break; 

} 

return handled; 


Further EventHandler refinement 

When an event occurs in the user interface, such as when a button is tapped on the 
device, a ctiSeiectEvent makes its way to the form event handler. The event 
handler examines the controllD of the event and dispatches it accordingly to another 
function named frmMain_HitMe_OnSeiect, listed below: 


static Boolean frmMain_HitMe_OnSelect(EventPtr event) 
{ 

// Insert code for HitMe 

FrmCustomAlert(Info,"Hi there",NULL,NULL); 
return true; 

} 


This function simply displays a message dialog with the words "Hi there." 

It is not necessary to break out each and every control or action to a separate function. 
This is a matter of organization, ultimately driven by programming style and readability. 
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Section 4. Simple application build and test 
Putting it all together 

The following instructions walkthrough the process of building a complete Palm OS 
application, complete with a single user interface element. The goal is to build an 
application exercising the topics discussed in this tutorial and test it on a Palm OS 
device, or on POSE. This also serves to validate the development tool installation and 
build environment. Space here does not permit a line-by-line guide through the 
process, so the following steps serve as an outline. Consider it a "cooking show" 
demonstration. (The Further resources on page 20 section at the end of this tutorial has 
a link to the full sample application project.) 


Step one: Create a new project 

1. Create a new project in Falch.net Developer Studio (or equivalent). 

2. Select Palm OS Framework Project. 

3. Give the project a name and location. 

4. A form named frmMain is automatically created. 

5. Leave the menu choice blank. 

6. Key in 'Info' and press the '+' (plus) button to add an alert to the project. An Alert 
is a user-interface element just like a MessageBox. 

7. Select the highest SDK value available and accept all other defaults. Leave the 
C++ box unchecked. 

8. Click on Finish. The project is now created and loaded into Developer Studio. 


Step two: Compile the project 

Press F7 to compile. This step should conclude with 'Compile Successful'. If the 
compilation is not successful, see the troubleshooting link in the Further resources on 
page 20 section at the end of this article. 


Step three: Create the 'Hit Me' button 

1. Expand the 'Resources' folder and double click on the file named 
yourprojectname.rcp. This is the resource script. An image of a Palm device 
appears along with a "toolbox" of user interface elements. 

2. In the toolbox, click on the 'OK' button. 

3. Draw a rectangle on the image of the Palm device. This creates a button on the 
form. 

4. In the Properties window, change the value of the ID from 'AUTOID' to 'HITME'. 
Change the Text value from 'New Button' to 'Flit Me'. 
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Step four: Create the message placeholder 

Under the 'Alerts' leaf in the middle of the screen, double click on 'Info'. In the 
Properties window to the right, change the default Message to simply read A 1. (That's 
shift+6 and then the digit 1.) This acts as a placeholder for a message provided 
dynamically at runtime. 


Step five: Assign a function to the button 

Select frmMain again, and highlight the newly created button and right mouse click. 
This presents a menu of options for Code Templates. Select 'Control Select Event'. 
This causes a new function to be added to the frmMain.c file. Enter the following line: 
FrmCustomAlert (Info, "Hi There" ,NULL, NULL) ; Note that CodeWarrior and 
PRC-Tools users must add this entire function themselves. Use the code snippets 
above as a guide, or download the entire application from the link provided in the 
Further resources on page 20 section. 


Step six: Recompile the project 

Press F7 to compile. If the compilation is not successful, see the troubleshooting link in 
the Further resources on page 20 section. 


Testing the application 

At this point, the application should be built. There are two options available for testing. 
The PRC file created during the build process can be installed directly to a device via 
the normal Palm Desktop install process. Tap on the yourprojectname icon in the 
application launcher on the Palm OS device to test out the application. 

Alternatively, POSE can be used. As mentioned earlier, POSE requires a valid Palm 
OS ROM file to run. If POSE is started without a valid configuration, it prompts for one. 
The choices are: Create a New configuration by selecting the target device, ROM file, 
and memory; or Open a previously used configuration. 

There are two ways to start the application in POSE. The first is to launch POSE 
independent of the development environment: Start POSE. Once started, right mouse 
click to select Install Application/Database, and then choose Other to browse the 
compiled application PRC file. The PRC is placed in a folder named Debug beneath 
the location of the project selected in Step 1 above. Click the right mouse and select 
Reset. When the emulator returns, tap the yourprojectname icon to test the application. 

Alternatively, POSE can be started from the Falch.net IDE: Simply press Ctrl-F5 and 
the emulator is launched with the application already running. 
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Break glass in case of emergency 

What if an application compiles cleanly but does not produce the desired output? All of 
the tools provide a debugging environment. Again, the instructions here refer to 
Falch.net's offering. 

Break points can be set by pressing F9 on a valid source line or via a mouse click in 
the left margin on a valid source line. F5 causes the program to run until a break point. 
F10 performs a step over and F11 performs a step into debug request. At this point, 
variable contents can be examined and modified. 

Although discussed in more detail in subsequent tutorials, it is important to note here 
that POSE provides special features for debugging communications programs. These 
include redirecting TCP/IP calls to the host system and redirecting Serial 
Communications to an available communications port on the host system. 
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Section 5. Build environment topics 


Makefiles versus IDE 

The instructions in this tutorial reference the Falch.net IDE. Building the application 
from the IDE involves menu choices or pressing the F7 key. As discussed earlier, 

Falch.net leverages GNU tools. This allows command-line compilation through the use 
of a makefile. Below is the makefile for the sample application. 

# 

# This MAKEFILE was automatically built with 

# Falch.net DeveloperStudio 2.5, and any 

# changes you make in this file will be overwritten 

# the next time you build this project. 

# 

# To edit this file manually, turn off "Automatically rebuild makefile on each build" 

# in the project settings dialog ( Project->Properties->Advanced Settings ) 

# 

# Target ALL 

all : ./Debug/getstarted.prc 

# Target Remove temporary files 
temp : 

cd ./Debug/ && \ 

rm -f *.bin bin.res *.grc *.o *. Id *.s *.d 

# Target Clean 
clean : 

cd ./Debug/ && \ 

rm -f *.bin bin.res *.grc *.prc *.o *. Id *.s *.d getstarted.prc getstarted 

# Rule for building sourcefile main.c 
./Debug/main.o : main.c 

@echo "Compiling main.c..." && \ 

m68k-palmos-gcc -palmos4.0 -g -o./Debug/main.o -c main.c -MD 
@mv main.d ./Debug/main.d 

# Rule for building sourcefile frmMain.c 
./Debug/frmMain.o : frmMain.c 

@echo "Compiling frmMain.c..." && \ 

m68k-palmos-gcc -palmos4.0 -g -o./Debug/frmMain.o -c frmMain.c -MD 
@mv frmMain.d ./Debug/frmMain.d 

# Rule for building resources 

./Debug/binOOOO.res : getstarted.rep 

@echo "Compiling resource getstarted.rep..." && \ 
pilrc -q getstarted.rep ./Debug/ 

# Rule for Linking the project 

./Debug/getstarted : ./Debug/main.o ./Debug/frmMain.o 

@echo "Linking..." && \ 

m68k-palmos-gcc ./Debug/main.o ./Debug/frmMain.o -palmos4.0 -g -o 

# Rule for postprocessing files 

./Debug/codeOOOO.getstarted.bin : ./Debug/getstarted 
@echo "Postprocessing files..." && \ 
cd ./Debug/ && \ 
obj-res getstarted 

./Debug/codeOOOl.getstarted.bin : ./Debug/codeOOOO.getstarted.bin 

./Debug/dataOOOO.getstarted.bin : ./Debug/codeOOOO.getstarted.bin 

# Rule for building PRCFile 

./Debug/getstarted.prc : ./Debug/binOOOO.res ./Debug/getstarted \ 

./Debug/codeOOOO.getstarted.bin ./Debug/codeOOOl.getstarted.bin \ 

./Debug/dataOOOO.getstarted.bin 

@echo "Building program file ./Debug/getstarted.prc..." && \ 
cd ./Debug/ && \ 

build-pre -t appl -o getstarted.prc -n "getstarted" -c ABCD *.grc *.bin 
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Makefile basics 

Here are a few of the pertinent details from the sample's Makefile: 

m68k-palmos-gcc -palmos4.0 -g -o./Debug/main.o -c main.c -MD 

This line compiles the main source file, including the SDK for Palm OS 4.0. The source 
file is marked by the '-o' option. The output file is indicated by the '-o' option. 

pilrc -q getstarted.rep ./Debug/ 


This line compiles the resource script to create all of the user-interface components. 
The output is a series of *.bin files. 


m68k-palmos-gcc ./Debug/main.o ./Debug/frmMain.o -palmos4.0 -g -o 

This line links the c object files into an executable form. The output is a series of *.grc 
files. 


build-pre -t appl -o getstarted.prc -n "getstarted" -c ABCD *.grc *.bin 


This line performs the post-linking process of combining the executable code 
(contained in *.grc files) with resources (contained in *.bin files). The name of the 
database is "getstarted." It has a database type of 'appl' and a creator id of 'ABCD.' 

The combination of database type and database creator id make the database unique 
for a given device. The output of this post-link process is 'getstarted.prc.' The output, 
getstarted.prc, represents the final output of the build process, and is the file installed 
to the device. 

Add the following locations to the system path to allow command-line compilation: 

C:\Progra~l\Falch.net\DeveloperStudio 2.5\bin\PrcTools\H-i586-cygwin32\bin; 
C:\Progra~l\Falch.net\DeveloperStudio 2.5\bin\Cygwin; 

C:\Progra~l\Falch.net\DeveloperStudio 2.5\bin\PilRC; 


Adjust these paths accordingly for the specific location of the installed tools. 


Static libraries 

Storing common routines in a shared library is an elegant technique to leverage 
pre-existing code. However, sometimes a static library is a more convenient 
mechanism. A static library is an archive file containing one or more object files. An 
object file is the output created by the C compiler. The linker uses the static library to 
satisfy function references made by the application. Falch.net does not have a project 
template for creating a static library. This section describes the steps to create a static 
library and how to reference that library from a Falch.net project. Additionally, this 
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example demonstrates use of the PRC-Tools from the command line. It is important to 
have the PRC-Tools included in the system path, as described above. 

First, compile a C source file containing a function. Here is an example: 


Filename: one.c 
#include <PalmOS.h> 
UInt8 dofunctionone() 
{ 

return 1; 

} 


Enter this from a command prompt to compile the file: 


m68k-palmos-ar r libmylibrary.a one.o 


The output of this command is one. o. 


Create the library makefile 

The next step creates a library to store this object code: 


m68k-palmos-ar r libmylibrary.a one.o 


To make this library available for linking into an application, take the following steps: 

Load the sample application built in the earlier step. Select the Project | Properties 
menu item. Click on the Linker tab. In the Additional Libraries edit box, type: mylibrary. 

Note that the lib prefix and the extension should not be included. Add the path to this 
file in the Additional library search paths edit box. The function named 
dofunctionone is now available for use in this project. The makefile changes to 
accommodate this library's inclusion in the link process: 

# Rule for Linking the project 

./Debug/getstarted : ./Debug/main.o ./Debug/frmMain.o 

@echo "Linking..." && \ 

m68k-palmos-gcc ./Debug/main.o ./Debug/frmMain.o -palmos4.0 -g -o 

-L"//c/Program Files/Falch.net/DeveloperStudio 2.5/Projects/libmylibrary" 

-lmylibrary 


Usage of the dofunctionone() 

The following code snippet demonstrates usage of this function in the sample 
application (note that this is normally done via an include file): 


// add a prototype for dofunctionone() 

UInt8 dofunctionone(); 

static Boolean frmMain_HITME_OnSelect(EventPtr event) 
{ 
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Char buf[50]; 

// Insert code for HITME 

StrPrintF(buf,"Here is a number: %d",dofunctionone()) ; 
FrmCustomAlert(Info,buf,NULL,NULL); 
return true; 

} 
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Section 6. Summary and further resources 
Summary and what's next 

This tutorial has established the baseline environment required for building Palm OS 
applications. Falch.net's product is highlighted for the sample application; however, any 
of the available C language suites will suffice. In addition to the development tool 
discussion, the basics of Palm OS application architecture have been presented. 
Material presented here is extended in the upcoming tutorial Communications and 
Database Programming. The sample applications found there explore the use of the 
Palm OS database and communications capabilities, moving toward a complete 
data-collection solution for Palm OS. 


Further resources 

* See the introductory article for this series, here on developerWorks 

* You can find more information on Palm OS User Interface development in this 
developerWorks article. 

* See this discussion relevant to the PRC-Toois distribution which is characterized 
as open source, or free software. 

* For the latest information on Palm OS Developer Information, visit: 
http://www.Palm OS.com/dev. 

* The full source to the sample application is available at 
http ://www.palm-communications, com/ibmdw . 

* For help setting up Developer Studio, visit Falch.net's Support page at 
http://www. falch.net/Support/. 

* For more information on the Palm OS Emulator (POSE) visit http://www.Palm 
OS.com/dev/tech/tools/emulator/. 

* Another resource on Palm OS Application Programming from O'Reilly & 
Associates: http://www. oreilly.com/catalog/palmprog2/ 


Feedback 

Please send us your feedback on this tutorial. We look forward to hearing from you! 


Colophon 

This tutorial was written entirely in XML, using the developerWorks Toot-O-Matic tutorial 
generator. The open source Toot-O-Matic tool is an XSLT stylesheet and several XSLT 
extension functions that convert an XML file into a number of PITML pages, a zip file, JPEG 
heading graphics, and two PDF files. Our ability to generate multiple text and binary formats 
from a single source file illustrates the power and flexibility of XML. (It also saves our 
production team a great deal of time and effort.) 

You can get the source code for the Toot-O-Matic at 
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www6.software.ibm.com/dl/devworks/dw-tootomatic-p. The tutorial Building tutorials with the 
Toot-O-Matic demonstrates how to use the Toot-O-Matic to create your own tutorials. 
developerWorks also hosts a forum devoted to the Toot-O-Matic; it's available at 
www-105.ibm.com/developerworks/xml_df.nsf/AIIViewTemplate?OpenForm&RestrictToCategory=11 . 
We'd love to know what you think about the tool. 
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